/*
 *
 * Copyright (C) 2010 Colibria AS
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */
package com.colibria.android.sipservice.endpoint.api;

import com.colibria.android.sipservice.MimeType;
import com.colibria.android.sipservice.MsrpRemoteAddress;
import com.colibria.android.sipservice.headers.ContentDispositionHeader;
import com.colibria.android.sipservice.headers.MsrpURI;
import com.colibria.android.sipservice.sip.Address;

import java.util.List;


/**
 * Provides a reference to a certain endpoint session.
 * <p/>
 * This is the interface for the endpoint application to
 * communicate with the endpoint session.
 *
 * @author Sebastian Dehne
 */
public interface IEndPointSession {

    /**
     * Gets the local msrpURI assosiated to this endpoint session
     *
     * @return the local msrpURI
     */
    public MsrpURI getLocalMsrpURI();

    /**
     * Request to establish an outboud connection for this endpoint session.
     * In case the endpoint session's current state doesn't allow this, this call will be ignored
     *
     * @param remoteAddress the remote URI to connect to
     */
    public void establishOutgoingConnection(MsrpRemoteAddress remoteAddress);

    /**
     * Sends either a new message or continues on a ongoing message by sending more data. The caller should ensure
     * that this is a connected endpoint session. See IMsrpEndpointApplication.connected().
     *
     * @param msgId                    the msgId of the ongoing msgs for which to transmit more data for. Set this to null
     *                                 in case a new message is being sent.
     * @param content                  The data which is to be sent for this integration
     * @param abortSending             whether the stack should abort sending this message
     * @param lastChunk                tells the msrp-stack that this is the last chunk for this message
     * @param contentType              the content-type of the message
     * @param recipients              list of recipients
     * @param contentDispositionHeader the Content-Disposition header to be sent
     * @param msgSize                  the message size. Should be -1 if unknown
     * @param sendingListener          the call-back listener which should be notified about the sending process
     * @return the messageID which was generated by the endpoint
     */
    public String sendNewMessage(
            String msgId,
            byte[] content,
            boolean abortSending,
            boolean lastChunk,
            MimeType contentType,
            List<Address> recipients,
            ContentDispositionHeader contentDispositionHeader,
            long msgSize,
            ISendingListener sendingListener);

    /**
     * Instructs the endPoint Session to send an "abort response" 413 for a certain incoming message in order to
     * ask the originator to cancel it
     *
     * @param msgID the message to be canceled
     */
    public void abortIncomingMessage(String msgID);

    /**
     * Causes the session to be closed
     */
    void close();
}
